The Programmer Disk/The Programmer Disk (Microforum).iso/xpro/basic1/pro9/fed.doc

Text File | 1987-07-31 | 18KB | 360 lines

                                Field Editor
                            Keyboard Input Handler

                             (C) InfoSoft, 1987


          I.       Introduction

        The care and use of FED can be a tad involved so it is documented
     separate from the rest of GIZLIB.  This does not mean that it can or
     may be distributed seperately from the rest of GIZLIB or FED.DOC.

        There are several (indeed many!) text input handlers around.  I
     know, because I have, or have looked at many of them.  Many of them
     require significant editing to work, or they are not modular, or they
     require the event trapping switch, or they were inadeqaute in
     functionality.  This is not to imply that FED is without its own
     failings, but overall, it is very flexible.

          FED, which originally stood for Field EDitor, is modular.  It can
     be called from the main code of another program very easily.

          As is, FED is very flexible in most every aspect.  You can change
     most all of the operating parameters with the change of a flag or
     two.

          Finally, FED does not require the use of any event trapping
     switch, it identifies extended key codes on its own, like most all good
     text input editors.



          II.          FED Files

       The key FED files are:
     FED-DEMO.BAS  - The demo
     EMP.DAT       - A random file of 7 or so records for the demo
     CHGFLD.SUB    - The FCODE handler from FED-DEMO that can be easily
                     modified for use in your program.
     FED.OBJ       - The BRUN30 object file.  Since I find FED very useful
                     and use it very often I have included the FED object
                     code to allow you to include it in other (BUILDLIB)
                     user libraries.  This object code will not successfully
                     run if linked to object modules compiled via the /o,
                     or BCOM30 option.


        The demo is a pretty simple random file allowing you to edit the
     various records in the file.  It is especially easy to use after
     reviewing this documentation.  You are encouraged to read this
     first so that as FED-DEMO executes, you can notice some of the key
     features.




        III.           FED Parameters, Syntax

          FED uses several switches and 3 arguments to control the flow
     and text input.  The formal or direct parameters are:

     TEXT$ - The original or old text string to edit.
     FSIZ  - An integer telling FED the maximum length allowed for the
             TEXT$, the current text to be edited.
     FCODE - The exit code returned by FED to tell you HOW they completed
             that field or what key was pressed upon exitting FED.

          You should understand that you can actually use any names that
     suit you in a call to a SUB...STATIC / END SUB subroutine.  That is,
     you could use ED$ instead of TEXT$, or T$, or whatever you want.  FED
     will operate just as expected, as long as you pass them in the right
     order.  The correct syntax:

     CALL fed(text$, fsiz%, fcode%)

          The importance of FSIZ is that FED will not allow input after that
     maximum size is reached, and maybe beep (bleep actually).  FED does not
     change FSIZ on the return, so be sure to reset it for each successive
     call.




          IV.        Incorporating FED to your code

        There are a few simple things to do to get FED running in your
     program:

        FED works off of 3 formal arguments (covered above) and several
     COMMON parameters shared with the main, calling program.  This
     allows you to share some parameters with FED very easily such as
     Foreground Color, upper casing etc.

        The actual use and meaning of these common parameters are covered
     later, here we are explaining how to set up for FED to work in your
     program.  This is done by simply including the following line in the
     beginning of your main code:

   COMMON /fedvars/ fg%, bg%, fgd%, bgd%, bleep%, edt%, nums%, num$, ucase%

        The meaning and use of the variables will be covered later, but in
     setting up FED for use, it is important that you list them EXACTLY as
     shown, ie in the order shown, WITH the type declarations.  The first
     four are foreground and background colors and the rest are listed
     alphabetically.



        Note that such COMMON statements must appear in your code BEFORE
     any executable statements.  If you are not familar with the use of
     COMMON it is suggested that you review pp 228-232 of the QB manual.
     Also refer to the FED-DEMO source for proper set up.  In implementing
     the FED variables, we have opted to make several of them COMMON to
     allow FED to read and literally share the value of these varibles
     with your main program and at the same time, keeps you from having to
     pass all of them as formal arguments to FED. That is, intead of:

     CALL fed(t$,fsiz,fcode, fg,bg, fgd,bgd, bleep, edt, nums,num$, ucase)
     all we do is:
     CALL fed(t$, fsiz, fcode)

        The use of a blockname (/fedvars/) prevents FED from interfering
     with other COMMON or COMMON SHARED variables, more precisely, it allows
     the USE of additional COMMON or COMMMON SHARED variables.  To name
     additional variables as COMMON declare them like this:

     DEFINT a-z
     COMMON /fedvars/ fg%, bg%, fgd%, bgd%, _
              bleep, edt%, nums%, num$, ucase%        ' FED block defined

     COMMON SHARED /newblock/ arg1, arg2, arg3        ' different block

     COMMON SHARED  a,_                               ' "blank" block of
                    b,_                               '   COMMON variables
                    c,_
                    z

        Note that /fedvars/ need not carry the SHARED attribute, but the use
     of a blockname allows FED to share those variables that it needs and
     ONLY those, ie a SIZE error is not encountered if you use other COMMON
     variables.  This allows for maximum flexibility.  Since you might only
     set many of the /fedvars/ such as fg, bg, fgd, bgd, and bleep once,
     they can be ignored after they are set.  Only edt, a more or less
     auxillary flag is altered by FED.  The only restriction in this is
     that unlike the formal arguments passed in the parentheses, the
     COMMON /fedvars/ variabls _MUST_ use the variable names shown.  That
     is, while t$ can be changed to text$ or fcode can be used as
     fed.return.code as you please, fg must be referenced as fg, fgd as fgd,
     edt as edt, ucase as ucase etc etc.



          V.         Internal Editting Keys

          Internally, FED does several things to provide a professional
     "look" to its operation.  First, lets look at the editing fiunctions
     and keys recognized:

     HOME     Places cursor at start of text or field.
     END      Places cursor at first blank at end of the text.


     Ctrl - End   Clear line from cursor to end of line.
     Ctrl - X     Clear all text from current field.
     Ctrl - U     Undoes current edit.  This does not restore the text to
                  it's form in a disk text file, but restores the text to
                  the form it was UPON ENTRY TO FED.  It cannot know what
                  the text was or what form it was in PRIOR to the CALL.



     Arrow Keys    Move one character Right or Left.  FED will not allow the
                   user to Cursor right into the hatched area if that
                   means that more than 1 space trails the text.  That is,
                   via the the right arrow, it will not allow more than 2
                   consecutive spaces, as in "J. DOE  " or "J Q  Public".
                   This can be achieved via the insert key however.


     Ctrl Arrow Keys   Moves one word right or left


     Ins     Insert works as expected, allowing text to be inserted at the
             cursor, and changes the cursor to a block.  The Insert state
             is toggled off upon exiting FED or "finishing" the field or
             text.


     Del     As expected, deletes characters to the right of the cursor.


       No key state flags (such as a [ INS ] or [ Caps ] indicator) are
     put to the screen.  This was viewed as intrusive in that where FED
     places the flag could be an unacceptable location in some applications,
     and it seemed to not be in the interest of speed, to be painting and
     repainting such indicators.




          VI.          FED Return Codes - FCODE

          This is the half of the meat of the program (The other half is
     internal).  FCODE return to you a value dependant on what key is
     pressed to complete the editing of the text.

          Needless to say, FED has undergown several forms and formats since
     I first started work on it.  The object of most changes has been to
     make the FCODEs more intuitive.  The current state may not seem to be
     as intuitive as they could be at first glance, but in keeping the dual
     goals of ease of use AND flexibility, but the actual FCODE handler
     (the routine called CHGFLD in FED-DEMO) can be "canned", or predone to
     be incorporated into your program.


                              FCODE Returns:

                             Enter   -    0
              F1      -    1                 F8      -    8
              F2      -    2                 F9      -    9
              F3      -    3                F10      -   10
              F4      -    4                PgUp     -   11
           Up Arrow   -    5                PgDn     -   12
           Dn Arrow   -    6              Ctrl-PgUp  -   13
              F7      -    7              Ctrl-PgDn  -   14
                             Escape  -    15


          Note that not EVERY possible key is trapped or returned.  Most
     notably, F5 and F6 are not trapped.   This is not because FED is lazy
     or dumb, but simply to cut down on the number of FCODES you need to
     handle (and handle whether your program uses or needs those codes or
     not) and to leave 2 keys open for response to any standing ON KEY() key
     traps your main program may need to have active at all times.

        I have used FED in several applications and more often than not, the
     keys trapped as is, are MORE than enough to do the job.   If you look
     at FED-DEMO you will see that it does quite a bit, in record paging,
     abort and save keys, and still has 3 or 4 FCODEs unused. In the long
     run, you should find that FED offers a suffient number of editting keys
     and with the use of a pre-done CHGFLD routine, it should be easy to
     handle the number of FCODES that it can return.

          The FCODEs returned, comply to the following rule: FCODE returns
     function keys as the number in it's "name": F1 is 1, F2 is 2 etc.  The
     top 4 Function keys and the bottom 4 are trapped.  F5 and F6 are
     skipped, so the Up Arrow and Dn Arrow return those FCODEs and then
     the bottom Function keys return their number.   Beyond that, the PgUp,
     PgDn and Ctrl-PgUp and Ctrl-PgDn are at the end, FCODEs 11, 12, 13 and
     14.  Finally, Enter is 0, and Escape is 15.

          Your distribution diskette or original archive should have a file
     called CHGFLD.SUB that can be easily edited (add a few RETURN <label>'s
     to it and paste it into your current code).  FED and CHGFLD together
     should make text input and data entry applications very easy and
     simple.  Throughout the demo, you can also note the integration of
     different GIZLIB functions and how they complement FED.




        VII.         Internal Handling, COMMON Parameters

         FED does a few things internally on its own and a few others you
     control and change throughout the course of your program by resetting
     the COMMON parameters.  If you are not familiar with SHARED parameters
     you should refer to your QB manual.  These are not passed as formal
     arguments inside the parentheses when the program is CALLed but are set
     in your main program.


       Using the value of FSIZ as the maximum length allowed, FED provides
     hatching from the end of the actual text to that maximum length.
     If a string is longer than FSIZ upon entry to FED, it is truncated to
     the maximum length.
     ( It is important to note that upon GETting a string from a random
     file, QB pads the string with spaces from the end of the text for the
     length of the FIELD.  That is, if you LSET "JOHN DOE" in a FIELD 15
     characters long, after a GET, the name becomes "JOHN DOE       ".  If
     you pass this as is to FED with a FSIZ of 15, no hatching will appear
     because FED does not distinguish the spaces as blank text or
     attempt to modify the string.  See STRIP in GIZLIB.)

     - FED also highlights the current text or data as well as providing
     the hatching.  When the editing is completed, and one of the 15 FCODE
     keys are hit to exit the field (actually FED is exitted, and control is
     returned to you), the highlighting is turned off.  This color control
     is handled thru the use of 2 sets of color codes: FG, BG and FGD and
     BGD.  These must be assigned valid BASIC color codes in the course of
     your main code.  At the start, FED uses the FGD, BGD (as in
     ForeGround_Data, BackGround_Data) colors and upon exitting, redisplays
     it in the FG, BG colors.  These only need to be set once.

     - Caps or uppercase input from the keyboard can be forced on the fly
     (ie without a sepoarate call) via the UCASE switch.  Set UCASE to 1 or
     non zero for caps, 0 for to allow either lower or upper case.

     - Numbers ONLY can be selected in the same manner with the switch
     NUMS.  When this is set, only numberic input is allowed, so to allow
     for a mixed string such as an address, NUMS should be OFF (nums=0).
     Additionally, you can redefine allowable characters for different
     entries via NUM$.  For example, in a phone number entry the characters
     "()-" may be allowable beyond 0-9, but in a dollar based entry $ and
     "." may be allowable.  So prior to the CALL for a phone entry NUM$
     would be set to "1234567890()-", and "1234567890$." for the dollar
     based entry.  This method of defining the entire string rather than
     just the extra ()-$ or . characters was chosen to allow category type
     entries too.  So, to force a category type chose from a set of 4
     choices, a NUM$="1234" or NUM$="1458" with NUMS=1, allows the user to
     choose a ONLY a character listed in NUM$.



     - If the text string upon exitting FED is different than it was at the
     start of the CALL to fed, then EDT is set to non-zero.  This allows you
     to test to see if field in a record has been altrered.  FED only sets
     it to 1 never to 0.  Since FED is just handling the input for different
     strings, it never knows when a set of fields equalling a full record is
     completed.  The EDT is how FED tells yopu that something has indeed
     been editted.
     ( Using this flag, you can include code in the CHGFLD routine to flash
     a message that an EDIT is in process, as is done in FED-DEMO.  It is
     also useful in precluding certain functions if an edited record is not
     saved.  An example of this is shown in FED-DEMO where paging is
     disallowed if a record is edited and unsaved.

     -  The final COMMON parameter to cover is BLEEP, this is a switch to
     indicate whether sound is to be on or off.  The sound is more of a
     bleep than a beep.  If this switch is set on (non zero) it allows the
     bleep sound effect to sound at various times:
     - An attempt to cursor right when the string has reached FSIZ (maximum
       length).
     - An attempt to enter an invalid character (an alpha character when
       nums is ON).
     - When an inserted character will cause the text to exceed the maximum
       length.
     - Cursor left attempted left of first character position.
     - If cursor right appends more than 1 successive blanks to the text.

       Regardless of the state of bleep, FED disregards any such illegal
     activities.  BLEEP just adds an error sound to the process.  While the
     error sound has it's uses, it is not recommended that it be on all the
     time - there are time when it is inappropriate.  For instance, if you
     allow 8 positions for a phone number as in xxx-xxxx, when the 8th
     character (7th number) is entered, the BLEEP error signal would sound.
     Since this is not REALLY an error, entries such as this should probably
     have BLEEP set to 0.  There are several examples of this in FED.

        In summary, the COMMON switch (0 or 1) parameters are:
     UCASE - Convert alpha input to Uppercase
     NUMS - Allow (numeric) input only from NUM$
     NUM$ - Character string of allowable input, if NUMS is not 0.
     FGD, BGD - Foreground and Background colors to diplay the string in
                while thsat strinmg is undergoing editing via FED.
     FG, BG - Colors FED restores the string to upon exiting the CALLed
              sub-program.
     EDT - Flag set by FED to show if text is changed.
     BLEEP - Switch to turn on or off BLEEPER error signal.